.\" Copyright 2023 Mozilla Foundation
.\"
.\" Licensed under the Apache License, Version 2.0 (the "License");
.\" you may not use this file except in compliance with the License.
.\" You may obtain a copy of the License at
.\"
.\"     http://www.apache.org/licenses/LICENSE-2.0
.\"
.\" Unless required by applicable law or agreed to in writing, software
.\" distributed under the License is distributed on an "AS IS" BASIS,
.\" WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
.\" See the License for the specific language governing permissions and
.\" limitations under the License.
.Dd December 5, 2023
.Dt ZIPALIGN 1
.Os Llamafile Manual
.Sh NAME
.Nm zipalign
.Nd PKZIP for LLMs
.Sh SYNOPSIS
.Nm
.Op FLAG...
.Ar ZIP
.Ar FILE...
.Sh DESCRIPTION
.Nm
adds aligned uncompressed files to a PKZIP archive.
.Pp
This tool is designed to concatenate gigabytes of LLM weights to an
executable. This command goes 10x faster than `zip -j0`. Unlike zip
you are not required to use the .com file extension for it to work.
But most importantly, this tool has a flag that lets you insert zip
files that are aligned on a specific boundary. The result is things
like GPUs that have specific memory alignment requirements will now
be able to perform math directly on the zip file's mmap()'d weights.
.Pp
This tool always operates in an append-only manner. Unlike the InfoZIP
.Xr zip 1
command,
.Nm
does not reflow existing assets to shave away space. For example, if
.Nm
is used on an existing PKZIP archive to replace an existing asset, then
the bytes for the old revision of the asset will still be there, along
with any alignment gaps that currently exist in the file between assets.
.Pp
The same concept also applies to the central directory listing that's
stored at the end of the file. When changes are made, the old central
directory is left behind as junk data. Therefore it's important, when
adding multiple files to an archive at once, that the files all be
passed in arguments at once, rather than calling this command multiple
times.
.Sh OPTIONS
The following options are available:
.Bl -tag -width indent
.It Fl h
Show help.
.It Fl v
Operate in verbose mode.
.It Fl N
Run in nondeterministic mode. This will cause the date/time of inserted
assets to reflect the file modified time.
.It Fl a Ar INT
Byte alignment for inserted zip assets. This must be a two power. It
defaults to 65536 since that ensures your asset will be page-aligned on
all conceivable platforms, both now and in the future.
.It Fl j
Strip directory components. The filename of each input filepath will be
used as the zip asset name. This is otherwise known as the basename. An
error will be raised if the same zip asset name ends up being specified
multiple times.
.It Fl 0
Store zip assets without compression. This is the default. This option
must be chosen when adding weights to a llamafile, otherwise it won't be
possible to map them into memory. Using
.Fl 0
goes orders of a magnitude faster than using
.Fl 6
compression.
.It Fl 6
Store zip assets with sweet spot compression. Any value between
.Fl 0
and
.Fl 9
is accepted as choices for compression level. Using
.Fl 6
will oftentimes go 10x faster than
.Fl 9
and only has a marginal increase of size. Note uncompression speeds are
unaffected.
.It Fl 9
Store zip assets with the maximum compression. This takes a very long
time to compress. Uncompression will go just as fast. This might be a
good idea when publishing archives that'll be widely consumed via the
Internet for a long time.
.El
.Sh SEE ALSO
.Xr unzip 1 ,
.Xr llamafile 1
.Sh AUTHORS
.An "Justine Alexandra Roberts Tunney" Aq jtunney@mozilla.com
